---
title: Switch
description: Switches are a pleasant interface for toggling a value between two states, and offer the same semantics and keyboard navigation as native checkbox elements.
author:
  name: imskyleen
  url: https://github.com/imskyleen
releaseDate: 2025-09-07
---

<ComponentPreview name="demo-primitives-headless-switch" />

## Installation

<ComponentInstallation name="primitives-headless-switch" />

## Usage

```tsx
<Switch>
  <SwitchIcon position="left" />
  <SwitchIcon position="right" />
  <SwitchThumb>
    <SwitchIcon position="thumb" />
  </SwitchThumb>
</Switch>
```

## API Reference

### Switch

<ExternalLink
  href="https://headlessui.com/react/switch#switch"
  text="Headless UI API Reference - Switch"
/>

<TypeTable
  type={{
    '...props': {
      description: 'The props of the Switch component.',
      type: 'HTMLMotionProps<"button">',
      required: false,
    },
  }}
/>

### SwitchThumb

<TypeTable
  type={{
    pressedAnimation: {
      description: 'The animation of the thumb when pressed.',
      type:
        'TargetAndTransition' |
        'VariantLabels' |
        'boolean' |
        'LegacyAnimationControls',
      required: false,
    },
    '...props': {
      description: 'The props of the SwitchThumb component.',
      type: 'HTMLMotionProps<"div">',
      required: false,
    },
  }}
/>

### SwitchIcon

<TypeTable
  type={{
    position: {
      description: 'The position of the icon.',
      type: 'left' | 'right' | 'thumb',
      required: true,
    },
    '...props': {
      description: 'The props of the SwitchIcon component.',
      type: 'HTMLMotionProps<"div">',
      required: false,
    },
  }}
/>

## Credits

- [Headless Switch](https://headlessui.com/react/switch)
